<html>
<head><meta charset="utf-8"><title>Async in documentation examples · general · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/index.html">general</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html">Async in documentation examples</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="219789901"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219789901" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219789901">(Dec 14 2020 at 00:28)</a>:</h4>
<p>Is there an easy way to use async code in documentation examples? Or is my best bet to use block_on?</p>



<a name="219889025"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219889025" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219889025">(Dec 14 2020 at 19:19)</a>:</h4>
<p>what kind of "use"?</p>



<a name="219889077"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219889077" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219889077">(Dec 14 2020 at 19:19)</a>:</h4>
<p>you could compile it without actually running it</p>



<a name="219890568"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219890568" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219890568">(Dec 14 2020 at 19:28)</a>:</h4>
<p>yea, I was hoping to also run it as its an easy way to ensure examples are valid and they can somewhat expand unit test coverage.</p>



<a name="219891579"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219891579" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219891579">(Dec 14 2020 at 19:35)</a>:</h4>
<p>Yeah, you'll want to bring one of the executors in then.</p>



<a name="219891650"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219891650" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219891650">(Dec 14 2020 at 19:36)</a>:</h4>
<p>you know how to hide things in doc tests though? With the leading <code>#</code>?</p>



<a name="219891685"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219891685" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219891685">(Dec 14 2020 at 19:36)</a>:</h4>
<p>You can add a little hidden main that calls your async function / block</p>



<a name="219891707"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219891707" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219891707">(Dec 14 2020 at 19:36)</a>:</h4>
<p>still a pain for you, but at least the code looks nice to the doc reader.</p>



<a name="219892147"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892147" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892147">(Dec 14 2020 at 19:40)</a>:</h4>
<p>That sound like the best option. I assume there is no way to share the code across across examples so its not full of copy pasting?</p>



<a name="219892222"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892222" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892222">(Dec 14 2020 at 19:41)</a>:</h4>
<p><span class="user-mention" data-user-id="371560">@Michael Carson</span> you could have a <code>doc(hidden)</code> public function in the main library</p>



<a name="219892237"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892237" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892237">(Dec 14 2020 at 19:41)</a>:</h4>
<p>Nothing I know of directly. ^</p>



<a name="219892259"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892259" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892259">(Dec 14 2020 at 19:41)</a>:</h4>
<p>I'd probably make it <code>cfg(doc)</code> as well</p>



<a name="219892282"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892282" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892282">(Dec 14 2020 at 19:41)</a>:</h4>
<p>or would it be test</p>



<a name="219892289"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892289" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892289">(Dec 14 2020 at 19:41)</a>:</h4>
<p>One or the other</p>



<a name="219892322"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892322" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892322">(Dec 14 2020 at 19:41)</a>:</h4>
<p>ideally it would be <code>cfg(doctest)</code> but <code>cfg(doctest)</code>is broken</p>



<a name="219892379"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892379" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892379">(Dec 14 2020 at 19:42)</a>:</h4>
<p>not sure if cargo sets <code>test</code> or <code>doc</code></p>



<a name="219892402"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892402" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892402">(Dec 14 2020 at 19:42)</a>:</h4>
<p><span class="user-mention" data-user-id="232545">@Joshua Nelson</span>  I'll look into that as well</p>



<a name="219892462"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892462" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892462">(Dec 14 2020 at 19:43)</a>:</h4>
<p>unsure if there is already a feature request for this but I think there is a good usecase for adding an # AsyncExamples block</p>



<a name="219892494"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892494" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892494">(Dec 14 2020 at 19:43)</a>:</h4>
<p>though having it be executor agnostic is probably semi-tough</p>



<a name="219892539"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892539" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892539">(Dec 14 2020 at 19:43)</a>:</h4>
<p>I think a general setup/teardown test framework is probably more general and helpful</p>



<a name="219892571"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892571" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892571">(Dec 14 2020 at 19:44)</a>:</h4>
<p>unfortunately that hasn't seen any movement in the last couple years :/</p>



<a name="219892688"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892688" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892688">(Dec 14 2020 at 19:44)</a>:</h4>
<p>I have been using the beta test framework for a code base that needed integration testing</p>



<a name="219892722"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892722" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892722">(Dec 14 2020 at 19:45)</a>:</h4>
<p>does that allow setup/teardown? I thought libtest ran each test in isolation</p>



<a name="219892882"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892882" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892882">(Dec 14 2020 at 19:46)</a>:</h4>
<p>You can define a test runner and then pass it a list of functions. Each file will run in isolation but within a file they run in the same "state space".</p>



<a name="219892914"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892914" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892914">(Dec 14 2020 at 19:46)</a>:</h4>
<p>ah hmm, that does sound useful</p>



<a name="219892993"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/Async%20in%20documentation%20examples/near/219892993" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Michael Carson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/Async.20in.20documentation.20examples.html#219892993">(Dec 14 2020 at 19:47)</a>:</h4>
<p>having shared code is still a pain though as its easy to get circular references. But its the best way I have found to do integration testing and still use cargo test.</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>